<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN">
<html>
<head>
<title>Introduction to org.jfonia.connect</title>
<meta name="Author" CONTENT="wijnand.schepens@hogent.be">
<style type="text/css">
.note { font-size: 8pt; }
h1 { font-size: 18pt; }
h2 { font-size: 14pt; }
h3 { font-size: 12pt ;}
pre { border: solid 1px; margin-top: 0px; margin-bottom: 0px}
</style>
</head>
<body>
<h1>Introduction to the package org.jfonia.connect</h1>

<p class="note">
[it is assumed the reader is familiar with basic concepts such as interfaces, auto-boxing, generics etc.]

<p>
The package <code>org.jfonia.connect</code> contains interfaces and classes
which are designed 
for a simple but powerful system of values, functions, procedures, events, iterators etc.

<p>
The building blocks are <i>nodes</i> which can be connected to send signals to each other.
There are many different types of nodes. Some of them have a <i>value</i>, some
can <i>execute</i> code, some can do both. Nodes can <i>listen</i> to other nodes, 
e.g. to respond to a change of some value... A set of coupled nodes forms a kind of 
<i>dependency graph</i>, hence the name <i>node</i>.


<p>
Three interfaces make up the core of the system: <code>Value</code>, <code>MutableValue</code> and <code>Callable</code>. 
Note that there is no basic class or interface called <code>Node</code>. Any class which implements one of the three interfaces can act as a node.

<h2>Value nes</h2>

<p>
The interface <b><code>Value</code></b> declares one method:
<pre>
interface Value&lt;T&gt; {
	T get();
}
</pre>
A node which implements <code>Value&lt;T&gt;</code> can <i>provide a value</i> of type <code>T</code>.
Examples: an object (variable or constant), a function-result, an array element, a collection element, an iterator-value etc. We'll call any class which implements this interface a <i>value node</i> (not to be confused with .NET value types)

<p class="note">
[Note: in Java, T cannot be a primitive. One has to use <code>Integer</code>, <code>Boolean</code> etc.]

<p>
The interface <b><code>MutableValue</code></b> extends <code>Value</code> and adds a set-method:
<pre>
interface MutableValue&lt;T&gt; extends Value&lt;T&gt; {
	void set(T newValue);
}
</pre>
Whereas <code>Value</code> nodes are "read-only", <code>MutableValue</code> nodes are "read/write".

<p class="note">
[Note that we chose to let <code>MutableValue</code> extend <code>Value</code>. 
This means that one cannot have a setter without a getter, as in a pure "out"-argument]

<h3>SimpleValue</h3>
<p>
The class <code>SimpleValue&lt;T&gt;</code> is - as the name suggests - a simple node type
which <i>stores</i> a value (an object) of type <code>T</code>:
<pre>
public class SimpleValue&lt;T&gt; implements MutableValue<T>
{
	protected T value;
	
	// constructors...

	public void set(T newValue) 
	{
		this.value = newValue;
	}
	
	public T get()
	{
		return value;
	}
}
</pre>
<p class="note">
[Note: this is a simplification: <code>SimpleValue</code> actually extends <code>Propagator</code> and provides a <code>call()</code>-method. The set-method is also simplified. See further]
<p>
This class acts as a "box" around an object of type <code>T</code>, much like <code>Integer</code> is a "box" around an <code>int</code>-value, with the important difference that <code>SimpleValue</code> is mutable, whereas <code>Integer</code> is immutable.

<h3>Function nodes</h3>

<p>
A "function node" doesn't store a value but calculates it (when requested, by a <code>get()</code>-call). The function value typically depends on other value nodes, which we
call <i>source-values</i>

<p>
An example function which adds two integers:
<pre>
public class IntAddition implements Value&lt;Integer&gt;
{
	private Value&lt;Integer&gt; source1;
	private Value&lt;Integer&gt; source2;
	
	public IntAddition(Value&lt;Integer&gt; source1, Value&lt;Integer&gt; source2) 
	{
		this.source1 = source1;
		this.source2 = source2;
	}

	public Integer get() 
	{
		return source1.get() + source2.get();
	}
}
<p class="note">
[Again, this is a simplication: in reality this class extends <code>Propagator</code>, has getters/setters etc.]

</pre>
Of course an <code>IntAddition</code>-source doesn't have to be a <code>SimpleValue</code>,
it can be any value node. In the following example this is illustrated by "cascading"
two additions:
<pre>
	MutableValue&lt;Integer&gt; a = SimpleValue&lt;Integer&gt;(5);
	MutableValue&lt;Integer&gt; b = SimpleValue&lt;Integer&gt;(10);
	MutableValue&lt;Integer&gt; c = SimpleValue&lt;Integer&gt;(20);
	Value&lt;Integer&gt; sum = new IntAddition(a, new IntAddition(b, c));
	System.out.println(sum.get());	// 35
	a.set(7);
	System.out.println(sum.get());	// 37
</pre>


<p>
Note: there is no class or interface called <code>Function</code>. It is a general term to
indicate any value node which responds to <code>get()</code> by calculating a value. One could also call
it "transformation"... jFonia will provide a set of basic function nodes for simple arithmetic, logic etc., as well as a set of function nodes useful for manipulating music information.

<p>
Note: a function may choose to store ("cache") the current function-value in order to prevent
unnecessary recalculation of the function value if <code>get()</code> is called more than once
while the source-values haven't changed. Such a caching function will normally "listen" to changes in the source-values (see further).


<h2>Callable nodes</h2>

<h3>interface <code>Callable</code></h3>

A node is "callable" when it implements the <code>Callable</code> interface:
<pre>
public interface Callable
{
	boolean call(Object parameter);
}
</pre>
The method <code>call()</code> returns <code>true</code> in case of "success". What that means
exactly depends on the particular implementation. In the same sense, the meaning of the parameter
is left to the implementation.

<p>
Two important families of callable nodes are
<li>"procedure nodes"
<li>value nodes which "listen" to changes in source value

<h3>Procedure nodes</h3>
<p>

A procedure node is a node which doesn't have a value, but which can execute some code when called.
An example:
<pre>
	public class HelloWorld implements Callable
	{
		public boolean call(Object parameter) 
		{
			System.out.println("Hello world!");
			return true;
		}
	}
</pre>
This procedure node doesn't depend on any values. The parameter is not used, and <code>call()</code> always returns true (indicating "success").

<p>
A procedure node may also depend on one or more value nodes. Example:
<pre>
public class Printer&lt;T&gt; implements Callable
{
	protected Value&lt;T&gt; source;
	
	public Printer(Value&lt;T&gt; source)
	{
		this.source = source;

	public boolean call(Object param)
	{
		System.out.print(source.get());
		return true;
	}
}
</pre>
<p class="note">
[Note: in reality the class <code>Printer</code> is somewhat more complicated, as it allows
other output streams as well...]

<p>
Trivial illustration:
<pre>
	Value&lt;Integer&gt; a = SimpleValue&lt;Integer&gt;(5);
	Callable printer = new Printer&lt;Integer&gt;(a);
	printer.call(null);		// writes 5
</pre>
The <code>null</code>-parameter is a dummy value and the returned <code>boolean</code> is ignored.

<h3>Change-listeners</h3>
<p>
The same mechanism (<code>call()</code>) is used to inform nodes about changes in (other) node values,
as in an observer pattern. Nodes which want to be informed about changes are called "target nodes".
They must "register" themselves with the source node(s).

<p>
A useful base class:
<pre>
public class Propagator implements Callable
{
	private ArrayList&lt;Callable&gt; callTargets = new ArrayList&lt;Callable&gt;();

	public void addCallTarget(Callable callable)
	{
		callTargets.add(callable);
	}
	
	public boolean call(Object param)
	{
		for (Callable c: callTargets)
			c.call(this);
		return ....;
	}
}
</pre>
<p class="node">
[note: in the actual implementation call() return true if any of the calls to targets returns true]
<p class="node">
[note: in this implementation targets are stored in an ArrayList. This means their order is preserved
and a target may appear more than once in the list. Also, there are currently no provisions for removing or querying targets... This might all be changed in future releases. ]

<p>
In this implementation <code>this</code> is passed as a parameter to the target calls. This 
allows target nodes to identify the call-source (there may be more than one for a given target!).
Of course this behaviour can be changed if necessary, perhaps to pass more information to the targets.
<p class="node">
[note: in contrast with many existing event-systems, only one parameter is passed in call(). In AWT/Swing for example an event passes two arguments: the source-object and a parameter, specific to the type of event. Here we deliberately chose one parameter of type Object, leaving the possibility to
pass a pair containing both source-node and parameter...]

<p>As an illustration consider this <code>Printer</code> which is called automatically if its source value changes:
<pre>
	MutableValue&lt;Integer&gt; a = SimpleValue&lt;Integer&gt;(5);
	Callable printer = new Printer&lt;Integer&gt;(a);
	a.addCallTarget(printer);
	s.set(10);	// writes 10
</pre>

<p class="node">
[A different design would be to pass the thing to be printed to the <code>Printer</code>-object 
by the call-parameter. However, we prefer to let the <code>Printer</code> query its source value 
by get() as a consequence of being called, as it is more in the spirit of the general system...]

<h3>Recapitulation</h3>

<p>
In general, <code>call()</code> is used to send a message to a node. Firing an event or 
starting a procedure are special cases.

<p>
The Object-parameter in call() can be used to give the message "content". As a rule the 
parameter is equal to the node which made the call (the "source")

<h2>How to use the connect-system</h2>

<p>
There are different ways in which one may use the connect-system.

<p>
Basically one needs to 
<li>define nodes
<li>interconnect them

<p>
A node is an instantiation of a class which implements one of the basic interfaces (see top). A number of basic node classes
are provided, but it is easy to make new ones.

<p>
There are two types of connections between nodes:
<li>nodes may "depend on" source value nodes (mutable or not)
<li>nodes may "call" other nodes, either to invoke a procedure or to inform about a change in value

<p>
To get started, it is most easy to combine nodes of prefabricated node types such as SimpleValue etc. 
When performance is critical one may choose to make specialized nodes which combine the task of several nodes.
One may also define new node types to connect with existing software, e.g. call library functions, use GUI-elements etc.



</body>
</html>
